<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>COS Event Channel Configuration</title>
    <!--  -->
  </head>

  <body>
    <CENTER>
    <h1>COS Event Channel Configuration</h1>
    </CENTER>

    <H3>Run-time Configuration</H3>

    <P>The new implementation of the COS Event Service uses a
      factory to build all the objects and strategies it requires.
      The factory can be dynamically loaded using ACE Service
      Configurator, this is extremely convenient because the factory
      can also parse options in the Service Configurator script file.
    </P>

    <P>The current implementation provides a default implementation
      for this Factory, this document describes the options used by
      this default implementation.
      Users can define their own implementation, with new ad-hoc
      strategies or with pre-selected strategies.
    </P>

    <H3>The configuration file</H3>

    <P>The COS channel uses the same service configurator
      file that the ORB uses, the default name for this file is
      <CODE>svc.conf</CODE>, but the ORB option
      <CODE>-ORBSvcConf</CODE> can be used to override this.
      The format of the file is described in detail in
      the service configurator documentation, but the relevant section
      for the event channel looks like this:
    </P>

<PRE>
# Comments go here...
# More comments if you want to...
static CEC_Factory "-CECDispatching reactive ....."
</PRE>

    <P>All the event service factory options start with
      <CODE>-CEC</CODE></P>


    <H3>The options</H3>

    <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
        <TR>
          <TH>Option</TH>
          <TH>Description</TH>
        </TR>
        <!-- <TR NAME="CECDispatching"> -->
        <TR>
          <TD><CODE>-CECDispatching</CODE>
            <EM>dispatching_strategy</EM>
          </TD>
          <TD>Select the dispatching strategy used by the COS
            event service. A <EM>reactive</EM> strategy will use the
            same thread that received the event from the supplier to
            push the event to all the consumers.
            The <EM>mt</EM> strategy will also use a pool of threads,
            but the thread to dispatch is randomly selected.
          </TD>
        </TR>

        <!-- <TR NAME="CECDispatchingThreads"> -->
        <TR>
          <TD><CODE>-CECDispatchingThreads</CODE>
            <EM>number_of_threads</EM>
          </TD>
          <TD>Select the number of threads used by the <EM>mt</EM>
            dispatching strategy.
          </TD>
        </TR>

        <!-- <TR NAME="CECProxyConsumerLock"> -->
        <TR>
          <TD><CODE>-CECProxyConsumerLock</CODE>
            <EM>lock_type</EM>
          </TD>
          <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or
            <EM>recursive</EM>) to synchronize access to the
            ProxyPushConsumer state.
          </TD>
        </TR>

        <!-- <TR NAME="CECProxySupplierLock"> -->
        <TR>
          <TD><CODE>-CECProxySupplierLock</CODE>
            <EM>lock_type</EM>
          </TD>
          <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or
            <EM>recursive</EM>) to synchronize access to the
            ProxyPushSupplier state.
          </TD>
        </TR>

        <!-- <TR NAME="CECUseORBId"> -->
        <TR>
          <TD><CODE>-CECUseORBId</CODE>
            <EM>orbid</EM>
          </TD>
          <TD>Set the name of the ORB used by the event service, only
            useful in applications that create multiple ORBs and
            activate the event service in one of them.
          </TD>
        </TR>

        <!-- <TR NAME="CECConsumerControl"> -->
        <TR>
          <TD><CODE>-CECConsumerControl</CODE>
            <EM>policy</EM>
          </TD>
          <TD>Select the consumer control policy (<EM>null</EM> or
            <EM>reactive</EM>) to detect and discard broken consumers.
          </TD>
        </TR>

        <!-- <TR NAME="CECSupplierControl"> -->
        <TR>
          <TD><CODE>-CECSupplierControl</CODE>
            <EM>policy</EM>
          </TD>
          <TD>Select the supplier control policy (<EM>null</EM> or
            <EM>reactive</EM>) to detect and discard broken suppliers.
          </TD>
        </TR>

        <!-- <TR NAME="CECConsumerControlPeriod"> -->
        <TR>
          <TD><CODE>-CECConsumerControlPeriod</CODE>
            <EM>period</EM>
          </TD>
          <TD>Set the period (in microseconds) used by the reactive
            consumer control policy to poll the state of the
            consumers.
          </TD>
        </TR>

        <!-- <TR NAME="CECSupplierControlPeriod"> -->
        <TR>
          <TD><CODE>-CECSupplierControlPeriod</CODE>
            <EM>period</EM>
          </TD>
          <TD>Set the period (in microseconds) used by the reactive
            supplier control policy to poll the state of the
            suppliers.
          </TD>
        </TR>

        <!-- <TR NAME="CECConsumerControlTimeout"> -->
        <TR>
          <TD><CODE>-CECConsumerControlTimeout</CODE>
            <EM>timeout</EM>
          </TD>
          <TD><P>Set the relative roundtrip timeout for push and pull
                 consumers.  The default is 10000 microseconds.
                 This relative roundtrip timeout is utilized
                 when each consumer attached to the supplier is queried.
                 If querying any one of the consumers times out, it may
                 be disconnected depending on the
                 -CECProxyDisconnectRetries setting.
              </P>
              <P>This option can also be referenced as
                 -CECConsumerControlRoundtripTimeout.
             </P>
         </TD>
        </TR>

        <!-- <TR NAME="CECSupplierControlTimeout"> -->
        <TR>
          <TD><CODE>-CECSupplierControlTimeout</CODE>
            <EM>timeout</EM>
          </TD>
          <TD><P>Set the relative roundtrip timeout for push or pull
                 suppliers.  The default is 10000 microseconds.
                 This relative roundtrip timeout is utilized
                 when each supplier attached to the consumer is queried.
                 If querying any one of the suppliers times out, it may
                 be disconnected depending on the
                 -CECProxyDisconnectRetries setting.
              </P>
              <P>This option can also be referenced as
                 -CECSupplierControlRoundtripTimeout.
             </P>
         </TD>
        </TR>

        <!-- <TR NAME="CECReactivePullingPeriod"> -->
        <TR>
          <TD><CODE>-CECReactivePullingPeriod</CODE>
            <EM>period</EM>
          </TD>
          <TD>Set the period (in microseconds) used by the reactive
            pulling strategy to poll all the PullSuppliers for an
            event.
          </TD>
        </TR>

        <!-- <TR NAME="CECConsumerOperationTimeout"> -->
        <TR>
          <TD><CODE>-CECConsumerOperationTimeout</CODE>
            <EM>timeout</EM>
          </TD>
          <TD>Set the relative roundtrip timeout for all operations (except
            &quot;pings&quot; due to reactive consumer control) on consumers.
            Reactive consumer control must be enabled for this option to take
            effect.  The units for <EM>timeout</EM> are microseconds.
            If a remote operation invoked on the consumer exceeds the timeout,
            then that consumer will be considered &quot;bad&quot; and will be
            disconnected from the event channel.
          </TD>
        </TR>

        <!-- <TR NAME="CECSupplierOperationTimeout"> -->
        <TR>
          <TD><CODE>-CECSupplierOperationTimeout</CODE>
            <EM>timeout</EM>
          </TD>
          <TD>Set the relative roundtrip timeout for all operations (except
            &quot;pings&quot; due to reactive supplier control) on suppliers.
            Reactive supplier control must be enabled for this option to take
            effect.  The units for <EM>timeout</EM> are microseconds.
            If a remote operation invoked on the supplier exceeds the timeout
            then that supplier will be considered &quot;bad&quot; and will be
            disconnected from the event channel.
          </TD>
        </TR>

        <!-- <TR NAME="CECProxyConsumerCollection"> -->
        <TR>
          <TD><CODE>-CECProxyConsumerCollection</CODE>
            <EM>flag[:flags]</EM>
          </TD>
          <TD><P>Configure the data structure and strategies used to
              implement collections of
              <CODE>ProxyPushConsumers</CODE> and
              <CODE>ProxyPullConsumers</CODE>.
              The argument is a colon separated list of flags, with
              the following semantics:
              <TABLE BORDER="1" CELLSPACING="2" CELLPADDING="0">
              <TR><TH>Flag</TH><TH>Description</TH>
              </TR>
              <TR>
                <TD>MT</TD>
                <TD>Use regular mutexes and/or condition
                  variables for serialization.
                </TD>
                </tr>
              <TR>
                <TD>ST</TD>
                <TD>Use null mutexes and/or condition
                  variables for serialization.
                </TD>
                </tr>
              <TR>
                <TD>LIST</TD>
                <TD>Implement the collection using an ordered list,
                  fast for iteration (i.e. during event dispatching),
                  but slow for insertion and removal (i.e. when
                  clients connect and disconnect from the EC).
                </TD>
                </tr>
              <TR>
                <TD>RB_TREE</TD>
                <TD>Implement the collection using a Red-Black tree,
                  slow for iteration (i.e. during event dispatching),
                  but fast for insertion and removal (i.e. when
                  clients connect and disconnect from the EC).
                </TD>
                </tr>
              <TR>
                <TD>IMMEDIATE</TD>
                <TD>Threads block until they can execute a change on
                  the data structure, the system must use other
                  approaches to guarantee that the iterators are not
                  invalidated during event dispatching.  For example,
                  use a separate dispatching thread.  Using this option
                  with the reactive values for any of the
                  -CECSupplierControl, -CECConsumerControl, or
                  -CECDispatching options may cause deadlocks.
                </TD>
                </tr>
              <TR>
                <TD>COPY_ON_READ</TD>
                <TD>Before initiating an iteration to dispatch events
                  (or similar tasks) a copy of the complete collection
                  is performed.
                  This solves most of the synchronization problems,
                  but introduces a significant source of overhead and
                  priority inversions on the critical path.
                </TD>
                </tr>
              <TR>
                <TD>COPY_ON_WRITE</TD>
                <TD>Similar to the previous one, but the copy is only
                  performed when needed.
                </TD>
                </tr>
              <TR>
                <TD>DELAYED</TD>
                <TD>Threads that need to change the collection can
                  detect if that change will invalidate iterators used
                  by other threads.
                  If so, the thread posts the change on a queue that
                  is executed once the collection is no longer in
                  use.
                </TD>
              </TR>
              </TABLE>
            </P>
          </TD>
        </TR>

        <!-- <TR NAME="CECProxySupplierCollection"> -->
        <TR>
          <TD><CODE>-CECProxySupplierCollection</CODE>
            <EM>flag[:flags]</EM>
          </TD>
          <TD><P>Configure the data structure and strategies used to
              implement collections of <CODE>ProxyPushSupplier</CODE>
              and <CODE>ProxyPullSupplier</CODE> objects.
              Use the same arguments as with the
              <CODE>CECProxyConsumerCollection</CODE> option.
            </P>
         </TD>
        </TR>

        <!-- <TR NAME="CECProxyDisconnectRetries"> -->
        <TR>
          <TD><CODE>-CECProxyDisconnectRetries</CODE>
            <EM>number of retries</EM>
          </TD>
          <TD><P>This determines the number of times a consumer or
                 supplier can be "unresponsive" before the supplier or
                 consumer control will disconnect it.  The default is zero
                 retries.
            </P>
         </TD>
        </TR>
      </TABLE>
    </P>

    <H3>The constructor</H3>

    <P>The <CODE>TAO_CEC_EventChannel</CODE> class implements the
      <CODE>CosEventChannelAdmin::EventChannel</CODE> interface;
      this class takes one mandatory and two optional parameters in
      its constructor:
    </P>

<PRE>
  TAO_CEC_EventChannel (const TAO_CEC_EventChannel_Attributes& attributes,
                        TAO_CEC_Factory* factory = 0,
                        int own_factory = 0);
</PRE>

    <P>The <CODE>factory</CODE> is an optional parameter to override
      the default strategy factory used by the event channel,
      the event channel will destroy the factory if the
      <CODE>own_factory</CODE> argument is true.
    </P>

    <P>The <CODE>attributes</CODE> parameter can be used to fine tune
      some of the algorithms and strategies used by the event channel,
      the default values are probably OK for most applications.
      Notice that the attributes include the POA used to activate the
      ConsumerAdmin, SupplierAdmin, ProxyPushConsumer,
      ProxyPushSupplier, ProxyPullConsumer and the ProxyPullSupplier
      objects;
      these POAs must have the <CODE>IMPLICIT_ACTIVATION</CODE> and the
      <CODE>SYSTEM_ID</CODE> policies (as the RootPOA does).
    </P>

    <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
        <TR><TH>Attribute</TH><TH>Description</TH></TR>

        <TR><TD><CODE>consumer_reconnect</CODE></TD>
          <TD>If the attribute is not zero then the same consumer can
            call <CODE>connect_push_consumer</CODE> on its
            ProxyPushSupplier multiple times to change its
            subscriptions;
            this is usually more efficient that disconnecting and
            connecting again.
          </TD>
        </TR>

        <TR><TD><CODE>supplier_reconnect</CODE></TD>
          <TD>If the attribute is not zero then the same supplier can
            call <CODE>connect_push_supplier</CODE> on its
            ProxyPushConsumer multiple times to change its
            publications;
            this is usually more efficient that disconnecting and
            connecting again.
          </TD>
        </TR>

        <TR><TD><CODE>disconnect_callbacks</CODE></TD>
          <TD>It not zero the event channel will send disconnect
            callbacks when a disconnect method is called on a Proxy.
            In other words, if a consumer calls
            <CODE>disconnect_push_supplier()</CODE> on its proxy the
            EC will invoke <CODE>disconnect_push_consumer()</CODE>
            on the consumer.  A similar thing is done for suppliers.
            It is a matter of debate what the spec requires for the
            regular event service.
          </TD>
        </TR>

        <TR><TD><CODE>busy_hwm</CODE></TD>
          <TD>When the delayed flag is set on proxy collections,
            this flag controls the maximum
            number of threads that can simultaneously iterate over the
            collection before blocking.
            It can be used to avoid starvation in delayed updates on
            the collection.
          </TD>
        </TR>

        <TR><TD><CODE>max_write_delay</CODE></TD>
          <TD>When the delayed flag is set on proxy collections,
            this flag controls the maximum
            number of threads that will initiate dispatching
            <B>after</B> a change has been posted.
            Any thread after that is blocked until the operations are
            performed.
            It can be used to completely stop starvation of delayed
            updates on the collection.
          </TD>
        </TR>

        <TR><TD><CODE>supplier_poa</CODE></TD>
          <TD>The POA used by the event channel to activate SupplierAdmin
            and SupplierProxy objects.
          </TD>
        </TR>

        <TR><TD><CODE>consumer_poa</CODE></TD>
          <TD>The POA used by the event channel to activate ConsumerAdmin
            and ConsumerProxy objects.
          </TD>
        </TR>

      </TABLE>
    </P>

    <P><HR><P>

      Back to the TAO <A HREF="index.html">components documentation</A>.
  </body>
</html>
